chrome.userScripts

説明

userScripts API を使用して、ユーザー スクリプトのコンテキストでユーザー スクリプトを実行します。

権限

userScripts

User Scripts API chrome.userScripts を使用するには、manifest.json に "userScripts" 権限を追加し、スクリプトを実行するサイトに "host_permissions" を追加します。

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

対象

Chrome 120 以降 MV3 以降

コンセプトと使用方法

ユーザー スクリプトは、ウェブページの外観や動作を変更するためにウェブページに挿入されるコード スニペットです。Content Scripts や chrome.scripting API などの他の拡張機能とは異なり、User Scripts API では任意のコードを実行できます。この API は、拡張機能パッケージの一部として出荷できないユーザー提供のスクリプトを実行する拡張機能に必要です。

userScripts API の使用を有効にする

拡張機能が userScripts API を使用する権限を取得した後、ユーザーは特定の切り替えボタンを有効にして、拡張機能が API を使用できるようにする必要があります。必要な具体的な切り替えと、無効にしたときの API の動作は、Chrome のバージョンによって異なります。

次のチェックを使用して、新規ユーザーのオンボーディング時などに、ユーザーが有効にする必要がある切り替えボタンを判断します。

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version > 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

以降のセクションでは、さまざまな切り替えボタンとその有効化方法について説明します。

Chrome バージョン 138 より前（デベロッパー モードの切り替え）

拡張機能のデベロッパーは、Chrome のインストールでデベロッパー モードをすでに有効にしています。ユーザーもデベロッパー モードを有効にする必要があります。

以下の手順をコピーして、ユーザー向けの拡張機能のドキュメントに貼り付けることができます。

  1. 新しいタブで chrome://extensions と入力して、[拡張機能] ページに移動します。（設計上、chrome:// URL はリンクできません）。

  2. [デベロッパー モード] の横にある切り替えスイッチをクリックして、デベロッパー モードを有効にします。

    デベロッパー モードの切り替えボタンがハイライト表示された Chrome 拡張機能ページ

    拡張機能ページ（chrome://extensions）

Chrome バージョン 138 以降（ユーザー スクリプトを許可する切り替えボタン）

[ユーザー スクリプトを許可する] 切り替えボタンは、各拡張機能の詳細ページ（chrome://extensions/?id=YOUR_EXTENSION_ID など）にあります。

以下の手順をコピーして、ユーザー向けの拡張機能のドキュメントに貼り付けることができます。

  1. 新しいタブで chrome://extensions と入力して、[拡張機能] ページに移動します。（設計上、chrome:// URL はリンクできません）。
  2. 拡張機能カードの [詳細] ボタンをクリックすると、拡張機能の詳細情報が表示されます。
  3. [ユーザー スクリプトを許可する] の横にある切り替えスイッチをクリックします。
拡張機能の詳細ページの [ユーザー スクリプトを許可する] 切り替えボタン
ユーザー スクリプトを許可する切り替えボタン（chrome://extensions/?id=abc...）

API の可用性を確認する

userScripts API はすべての Chrome バージョンで動作するため、次のチェックで有効になっているかどうかを確認することをおすすめします。このチェックは、API が使用可能な場合は常に成功する chrome.userScripts() メソッドの呼び出しを試みます。この呼び出しでエラーがスローされた場合、API は使用できません。

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

分離されたワールドで作業する

ユーザー スクリプトとコンテンツ スクリプトはどちらも、分離されたワールドまたはメインワールドで実行できます。分離されたワールドは、ホストページや他の拡張機能からアクセスできない実行環境です。これにより、ユーザー スクリプトは、ホストページや他の拡張機能のユーザー スクリプトとコンテンツ スクリプトに影響を与えることなく、JavaScript 環境を変更できます。逆に、ユーザー スクリプト（およびコンテンツ スクリプト）は、ホストページや他の拡張機能のユーザー スクリプトやコンテンツ スクリプトには表示されません。メインワールドで実行されるスクリプトは、ホストページや他の拡張機能からアクセス可能で、ホストページや他の拡張機能に表示されます。世界を選択するには、userScripts.register() を呼び出すときに "USER_SCRIPT" または "MAIN" を渡します。

USER_SCRIPT ワールドのコンテンツ セキュリティ ポリシーを構成するには、userScripts.configureWorld() を呼び出します。

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

メッセージ

コンテンツ スクリプトとオフスクリーン ドキュメントと同様に、ユーザー スクリプトはメッセージングを使用して拡張機能の他の部分と通信します（つまり、拡張機能の他の部分と同様に runtime.sendMessage() と runtime.connect() を呼び出すことができます）。ただし、専用のイベント ハンドラを使用して受信されます（つまり、onMessage や onConnect は使用しません）。これらのハンドラは runtime.onUserScriptMessage と runtime.onUserScriptConnect と呼ばれます。専用のハンドラを使用すると、信頼性が低いコンテキストであるユーザー スクリプトからのメッセージを簡単に識別できます。

メッセージを送信する前に、messaging 引数を true に設定して configureWorld() を呼び出す必要があります。csp 引数と messaging 引数の両方を同時に渡すことができます。

chrome.userScripts.configureWorld({
  messaging: true
});

拡張機能の更新

ユーザー スクリプトは、拡張機能の更新時に削除されます。拡張機能サービス ワーカーの runtime.onInstalled イベント ハンドラでコードを実行すると、これらの機能を再度追加できます。イベント コールバックに渡された "update" の理由にのみ応答します。

例

この例は、サンプル リポジトリの userScript サンプルから取ったものです。

スクリプトを登録する

次の例は、register() の基本的な呼び出しを示しています。最初の引数は、登録するスクリプトを定義するオブジェクトの配列です。ここに表示されているオプション以外にも、さまざまなオプションがあります。

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

型

ExecutionWorld

ユーザー スクリプトが実行される JavaScript の世界。

列挙型

「MAIN」
DOM の実行環境を指定します。これは、ホストページの JavaScript と共有される実行環境です。

「USER_SCRIPT」
ユーザー スクリプトに固有の実行環境を指定し、ページの CSP の適用対象から除外します。

InjectionResult

Chrome 135 以降

プロパティ

  • documentId

    文字列

    挿入に関連付けられたドキュメント。

  • エラー

    文字列 省略可

    エラー（ある場合）。error と result は相互に排他的です。

  • frameId

    数値

    挿入に関連付けられたフレーム。

  • 件の結果

    任意

    スクリプト実行の結果。

InjectionTarget

Chrome 135 以降

プロパティ

  • allFrames

    ブール値（省略可）

    スクリプトをタブ内のすべてのフレームに挿入するかどうか。デフォルトは false です。frameIds が指定されている場合は、true にできません。

  • documentIds

    string[] 省略可

    挿入する特定の documentId の ID。frameIds が設定されている場合は、この値は設定しないでください。

  • frameIds

    number[] 省略可

    挿入する特定のフレームの ID。

  • tabId

    数値

    挿入するタブの ID。

RegisteredUserScript

プロパティ

  • allFrames

    ブール値（省略可）

    true の場合、タブ内の最上位のフレームでなくても、すべてのフレームに挿入されます。各フレームは URL 要件について個別にチェックされます。URL 要件が満たされていない場合、子フレームには挿入されません。デフォルトは false で、最上位のフレームのみが照合されます。

  • excludeGlobs

    string[] 省略可

    このユーザー スクリプトを挿入しないページのワイルドカード パターンを指定します。

  • excludeMatches

    string[] 省略可

    このユーザー スクリプトが挿入されるページを除外します。これらの文字列の構文の詳細については、一致パターンをご覧ください。

  • id

    文字列

    API 呼び出しで指定されたユーザー スクリプトの ID。このプロパティは、生成されるスクリプト ID の接頭辞として予約されているため、先頭に「_」を付けないでください。

  • includeGlobs

    string[] 省略可

    このユーザー スクリプトを挿入するページのワイルドカード パターンを指定します。

  • js

    ScriptSource[] 省略可

    一致するページに挿入されるスクリプトのソースを定義する ScriptSource オブジェクトのリスト。このプロパティは ${ref:register} に指定する必要があります。指定する場合は、空でない配列にする必要があります。

  • 一致

    string[] 省略可

    このユーザー スクリプトを挿入するページを指定します。これらの文字列の構文の詳細については、一致パターンをご覧ください。このプロパティは ${ref:register} に指定する必要があります。

  • runAt

    RunAt 省略可

    JavaScript ファイルがウェブページに挿入されるタイミングを指定します。推奨されるデフォルト値は document_idle です。

  • 世界

    ExecutionWorld（省略可）

    スクリプトを実行する JavaScript 実行環境。デフォルト値は `USER_SCRIPT` です。

  • worldId

    文字列 省略可

    Chrome 133 以降

    実行するユーザー スクリプトのワールド ID を指定します。省略すると、スクリプトはデフォルトのユーザー スクリプト ワールドで実行されます。world が省略されているか USER_SCRIPT の場合にのみ有効です。先頭にアンダースコア（_）が付いた値は予約済みです。

ScriptSource

プロパティ

  • コード

    文字列 省略可

    挿入する JavaScript コードを含む文字列。file または code のいずれか 1 つを指定する必要があります。

  • ファイル

    文字列 省略可

    拡張機能のルート ディレクトリを基準とする、挿入する JavaScript ファイルのパス。file または code のいずれか 1 つを指定する必要があります。

UserScriptFilter

プロパティ

  • ids

    string[] 省略可

    getScripts は、このリストに指定された ID のスクリプトのみ返します。

UserScriptInjection

Chrome 135 以降

プロパティ

  • injectImmediately

    ブール値（省略可）

    ターゲットでできるだけ早く挿入をトリガーするかどうか。ただし、スクリプトがターゲットに到達するまでにページがすでに読み込まれている場合があるため、ページの読み込み前に挿入が行われるとは限りません。

  • ターゲットに挿入されるスクリプトのソースを定義する ScriptSource オブジェクトのリスト。

  • ターゲット

    InjectionTarget

    スクリプトを挿入するターゲットを指定する詳細。

  • 世界

    ExecutionWorld（省略可）

    スクリプトを実行する JavaScript の「世界」。デフォルト値は USER_SCRIPT です。

  • worldId

    文字列 省略可

    実行するユーザー スクリプトのワールド ID を指定します。省略すると、スクリプトはデフォルトのユーザー スクリプト ワールドで実行されます。world が省略されているか USER_SCRIPT の場合にのみ有効です。先頭にアンダースコア（_）が付いた値は予約済みです。

WorldProperties

プロパティ

  • csp

    文字列 省略可

    世界 csp を指定します。デフォルトは `ISOLATED` 世界 csp です。

  • メッセージング

    ブール値（省略可）

    メッセージ アプリの API を公開するかどうかを指定します。デフォルト値は false です。

  • worldId

    文字列 省略可

    Chrome 133 以降

    更新する特定のユーザー スクリプト ワールドの ID を指定します。指定しない場合、デフォルトのユーザー スクリプト ワールドのプロパティが更新されます。先頭にアンダースコア（_）が付いた値は予約済みです。

メソッド

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

`USER_SCRIPT` 実行環境を構成します。

パラメータ

  • プロパティ

    WorldProperties

    ユーザー スクリプトのワールド構成が含まれています。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

execute()

Promise Chrome 135 以降 
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

スクリプトをターゲット コンテキストに挿入します。デフォルトでは、スクリプトは document_idle で実行されます。ページがすでに読み込まれている場合は、すぐに実行されます。injectImmediately プロパティが設定されている場合、ページの読み込みが完了していなくても、スクリプトは待機せずに挿入されます。スクリプトが Promise に評価された場合、ブラウザは Promise が解決されるのを待ってから、結果の値を返します。

パラメータ

戻り値

  • Promise<InjectionResult[]>

    Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

この拡張機能に対して動的に登録されたすべてのユーザー スクリプトを返します。

パラメータ

  • フィルタ

    UserScriptFilter（省略可）

    指定した場合、このメソッドは一致するユーザー スクリプトのみ返します。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (scripts: RegisteredUserScript[]) => void

戻り値

  • Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getWorldConfigurations()

Promise Chrome 133 以降 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

登録されているすべてのワールド構成を取得します。

パラメータ

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (worlds: WorldProperties[]) => void

戻り値

  • Promise<WorldProperties[]>

    Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

この拡張機能に 1 つ以上のユーザー スクリプトを登録します。

パラメータ

  • スクリプト

    RegisteredUserScript[]

    登録するユーザー スクリプトのリストが含まれています。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

resetWorldConfiguration()

Promise Chrome 133 以降 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

ユーザー スクリプト ワールドの設定をリセットします。指定された ID でワールドに挿入されるスクリプトは、デフォルトのワールド構成を使用します。

パラメータ

  • worldId

    文字列 省略可

    再設定するユーザー スクリプト ワールドの ID。省略した場合は、デフォルトのワールドの構成がリセットされます。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

この拡張機能に対して動的に登録されたすべてのユーザー スクリプトを登録解除します。

パラメータ

  • フィルタ

    UserScriptFilter（省略可）

    指定した場合、このメソッドは一致するユーザー スクリプトのみ登録解除します。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

update()

Promise 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

この拡張機能の 1 つ以上のユーザー スクリプトを更新します。

パラメータ

  • スクリプト

    RegisteredUserScript[]

    更新するユーザー スクリプトのリストが含まれています。プロパティが更新されるのは、このオブジェクトで指定されている場合に限られます。スクリプトの解析またはファイルの検証中にエラーが発生した場合、または指定された ID が完全に登録されたスクリプトに対応していない場合、スクリプトは更新されません。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。